Skip to content

小机云设备校验 ​

设备需要使用小机云服务,需要与小机云平台进行校验

小机云设备的设备校验,只需要向模块设置您的项目信息,然后重启即可

第三方设备自己需要实现校验流程

校验方法:HMAC 挑战应答 ​

设备连接后,通过二进制帧与手机进行挑战应答握手。设备用 ProjectSecret 对「MAC + 时间戳」计算 HMAC-SHA256 摘要,发送给手机转交服务器验证

相比内容校验(KeyContent),HMAC 方式报文更短(全程二进制,最小单包仅 1 字节)、固件代码更简洁、安全性更高

第一步:获取项目密钥

  • 进入小机云控制台并登录。登录后,点击项目卡片更多查看项目详情
  • 点击查看项目秘钥(ProjectSecret)

注意

HMAC 校验方式的项目,ProjectSecret 直接作为 HMAC 密钥使用,不需要进行 AES 加密。

握手流程 ​

整个握手使用二进制帧传输(非 $X 文本协议),流程如下:

设备                          手机App                        服务器
 │                              │                             │
 │  ① AE 01 00                  │                             │
 │ ────────────────────────────→│                             │
 │                              │                             │
 │  ② AE 02 04 [时间戳 4字节]    │                             │
 │ ←────────────────────────────│                             │
 │                              │                             │
 │  ③ AE 03 08 [digest 8字节]    │                             │
 │ ────────────────────────────→│  ④ 调用 verifyHmac 接口      │
 │                              │ ───────────────────────────→│
 │                              │                             │ ⑤ 重算比较
 │                              │  ⑥ 返回校验结果              │
 │                              │ ←───────────────────────────│
 │  ⑦ AE 0F 01 02 成功           │                             │
 │     或 AE 0E 01 reason 失败   │                             │
 │ ←────────────────────────────│                             │

各帧详细说明 ​

所有帧都带 0xAE 帧头,格式为 [0xAE][CMD][LEN][PAYLOAD]:

步骤方向帧内容字节数说明
①设备→AppAE 01 003设备请求挑战,无负载
②App→设备AE 02 04 [时间戳 4字节]7App 生成当前 UTC 秒级时间戳,大端序
③设备→AppAE 03 08 [digest 8字节]11设备计算 HMAC 摘要,截断取前 8 字节
⑦App→设备AE 0F 01 [reason] / AE 0E 01 [reason]4成功 / 失败,reason 见下表

结果码 reason ​

CMDreason含义
0x0F0x01命中本地缓存,直接通过
0x0F0x02服务器校验通过
0x0E0x02校验失败(摘要不匹配)
0x0E0x03失败次数过多,设备被临时锁定
0x0E0x04未通过鉴权就发送了数据帧

早期文档写的 0x04 成功 / 0x05 失败已废弃,固件请按 0x0F / 0x0E 实现。

时间戳说明 ​

  • 时间戳为 4 字节大端序 的 UTC 秒级 Unix 时间戳(非 13 位毫秒)
  • 服务器会校验时间戳与当前时间差不超过 5 分钟,防止重放攻击
  • 手机 App 在发送挑战时记住时间戳,收到设备摘要后连同时间戳一起提交给服务器验证

实现校验方法 ​

您可以自己在单片机中实现校验流程,也可以使用小机云调试工具快速体验校验流程

如果需要自己实现校验流程,可以跳过使用小机云调试工具体验这一过程

自己实现校验流程 ​

设备与项目各项属性为:

projectId:1032n8e32sa9v2bdf3

mac:112233445566(需要与创建设备时输入的MAC一致)

ProjectSecret:B407CEA9A9DA7B9A088F81D42E217444

握手过程示例:

① 设备发送挑战请求

发送:AE 01 00

收到 App 回复:AE 02 04 67 89 AB CD(时间戳 0x6789ABCD = 1736543181)

② 设备计算 HMAC

原文 = mac(6字节) + timestamp(4字节大端)

原文(10字节):11 22 33 44 55 66 67 89 AB CD

密钥(字符串):B407CEA9A9DA7B9A088F81D42E217444

HMAC-SHA256 计算结果(32字节),取前 8 字节作为摘要

③ 设备发送摘要

假设 HMAC 计算结果前 8 字节为:A1 B2 C3 D4 E5 F6 07 18

发送:AE 03 08 A1 B2 C3 D4 E5 F6 07 18

校验成功收到:AE 0F 01 02

校验失败收到:AE 0E 01 02

单片机 Demo

可以参考开源项目中的《xsgee-esp32-ble-arduino》

ESP32 Arduino 参考代码(约 15 行核心逻辑):

cpp
#include <mbedtls/md.h>

// 收到挑战时间戳后计算 HMAC
void computeHmac(const char* secret, const uint8_t* mac, uint32_t timestamp, uint8_t* out) {
    uint8_t msg[10];
    memcpy(msg, mac, 6);
    msg[6] = (timestamp >> 24) & 0xFF;
    msg[7] = (timestamp >> 16) & 0xFF;
    msg[8] = (timestamp >> 8) & 0xFF;
    msg[9] = timestamp & 0xFF;

    uint8_t full[32];
    mbedtls_md_context_t ctx;
    mbedtls_md_init(&ctx);
    mbedtls_md_setup(&ctx, mbedtls_md_info_from_type(MBEDTLS_MD_SHA256), 1);
    mbedtls_md_hmac_starts(&ctx, (const uint8_t*)secret, strlen(secret));
    mbedtls_md_hmac_update(&ctx, msg, sizeof(msg));
    mbedtls_md_hmac_finish(&ctx, full);
    mbedtls_md_free(&ctx);

    memcpy(out, full, 8); // 截断取前 8 字节
}

与内容校验(KeyContent)的对比 ​

对比项内容校验(KeyContent)HMAC 挑战应答
传输格式$X 文本协议 + hex 字符串二进制帧
加密方式AES/ECB/PKCS7 256HMAC-SHA256
报文长度较长(需拼接多个字段再加密)最短 3 字节(挑战请求),摘要帧 11 字节
固件代码量约 400 行(含 AES)约 15 行(mbedTLS)
安全性AES-ECB 模式,相同明文产生相同密文标准 MAC,恒等比较防时序攻击
时间戳精度13 位毫秒4 字节秒级
MTU 要求需支持较长 MTU 或分包最小 20 字节 MTU 即可完成
适用场景兼容老设备/老固件新设备推荐,尤其低端 BLE 模块

相关文档 ​